Documentation

# CoPilot Agent Configuration

Defines a CoPilot Agent (Declarative Agent) that deploys a .agent JSON file to a SharePoint document library or folder, enabling a Microsoft 365 Copilot assistant scoped to that content.

Referenced by: DocLibCfg.CoPilotAgents, FolderCfg.CoPilotAgents, SharepointCfg.CoPilotAgentDefinitionCfgs.

# Overview

CoPilotAgentDefinitionCfg is defined once in SharepointCfg.CoPilotAgentDefinitionCfgs and referenced by name from DocLibCfg.CoPilotAgents or FolderCfg.CoPilotAgents. The same definition can be reused across multiple libraries or folders. When provisioned, it generates a .agent JSON file that configures a Microsoft 365 Copilot assistant scoped to the documents in that library or folder.

Official Microsoft documentation: Declarative agents for Microsoft 365 Copilot (opens new window)

# Applied when

Agent files are deployed:

  • Library root — when the document library is first created, or on every provisioning run when DocLibCfg.AlwaysDeployAgentFiles = true
  • Folder — when a folder is first created, or on every provisioning run when FolderCfg.AlwaysDeployAgentFiles = true

If an .agent file already exists at the target path it is overwritten.

# Core settings

# Name

Type: string | Default: — | Required: Yes

Unique name. Referenced from DocLibCfg.CoPilotAgents or FolderCfg.CoPilotAgents.

Example: "MatterAgent", "ContractsAgent"

# AgentName

Type: string | Default: — | Required: Yes

Display name of the agent shown to users in Microsoft 365 Copilot. Supports dynamic name substitution.

Example: "{MatterName} Documents", "Contracts Assistant"

# Instructions

Type: string | Default: — | Required: Yes

System prompt that defines the agent's behavior, tone, and focus area. This is the most important field — it shapes how the agent responds to users. Supports dynamic name substitution.

Example: "You are an assistant for the {MatterName} matter. Answer questions based on the documents in this library only."

# AgentFileName

Type: string | Default: {AgentName}.agent | Required: No

Output filename for the .agent file. The .agent extension is added automatically if omitted. Invalid SharePoint filename characters are stripped automatically. Supports dynamic name substitution.

Example: "{MatterCode}.agent" — produces M-2024-001.agent

# Description

Type: string | Default: — | Required: No

Short description of the agent's purpose, shown to users in the agent selection UI. Supports dynamic name substitution.

Example: "Assistant for {MatterName} — answers questions about matter documents."

# WelcomeMessage

Type: string | Default: — | Required: No

Message displayed when a user starts a new conversation with the agent. Supports dynamic name substitution.

Example: "Hello! I can help you find information in the {MatterName} documents."

# ConversationStarters

Type: string (list) | Default: — | Required: No

Up to 6 suggested prompts shown to users when they open the agent. Supports dynamic name substitution in each entry.

Example: ["Summarize the key documents", "What are the latest correspondence items?"]

# Icon

Type: string | Default: — | Required: No

Base64-encoded icon data URI displayed alongside the agent in the Copilot UI.

Example: "data:image/png;base64,iVBORw0KGgo..."

# DiscourageModelKnowledge

Type: bool | Default: true | Required: No

When true, instructs the agent to answer only from the configured content scope and not draw on general model knowledge. Set to false to allow the agent to blend library content with general knowledge.

# Scope

Scope is determined automatically based on deployment context:

Deployment Content scope in generated .agent
Via DocLibCfg.CoPilotAgents The document library URL
Via FolderCfg.CoPilotAgents The specific folder URL within the library

# Dynamic name substitution

All text properties support {PropertyName} placeholders resolved at provisioning time from the site's dynamic properties (e.g. {MatterName}, {MatterCode}, {ClientName}, {ClientCode}).

# Generated .agent file

Example of the .agent file generated for a library-scoped agent:

{
  "schemaVersion": "0.2.0",
  "customCopilotConfig": {
    "conversationStarters": {
      "conversationStarterList": [
        { "text": "Summarize the key documents" },
        { "text": "What are the latest correspondence items?" }
      ],
      "welcomeMessage": {
        "text": "Hello! I can help you find information in these documents."
      }
    },
    "gptDefinition": {
      "name": "Contoso Matter Documents",
      "description": "Assistant for the Contoso matter",
      "instructions": "You are an assistant for the Contoso matter...",
      "capabilities": [
        {
          "name": "OneDriveAndSharePoint",
          "items_by_sharepoint_ids": [],
          "items_by_url": [
            {
              "url": "https://tenant.sharepoint.com/sites/mysite/Shared%20Documents",
              "site_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "web_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "list_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "unique_id": "00000000-0000-0000-0000-000000000000",
              "type": "Folder"
            }
          ]
        }
      ],
      "behavior_overrides": {
        "special_instructions": {
          "discourage_model_knowledge": true
        }
      }
    }
  }
}

For folder-scoped agents the url points to the specific folder URL.

Last Updated: 4/20/2026, 12:54:05 PM